Add analysis pipeline

This commit is contained in:
dahyeon committed 2026-07-02 20:40:49 -07:00
1 parent 256d776131
commit 770c198ccd
20 files changed
+2572 -1

No files matched your search

+2
View File
@@ -20,11 +20,13 @@
},
"dependencies": {
"@infisical/sdk": "^5.0.2",
"@nestjs/bullmq": "^11.0.4",
"@nestjs/common": "^11.0.1",
"@nestjs/config": "^4.0.4",
"@nestjs/core": "^11.0.1",
"@nestjs/platform-express": "^11.0.1",
"@persona-lenz/shared": "workspace:*",
"bullmq": "^5.79.2",
"mongoose": "^9.7.3",
"redis": "^5.12.1",
"reflect-metadata": "^0.2.2",
+47
View File
@@ -0,0 +1,47 @@
import { getQueueToken } from '@nestjs/bullmq';
import { Test } from '@nestjs/testing';
import { AppModule } from './app.module';
import { AnalysisQueueService } from './modules/analysis/analysis-queue.service';
import { ANALYSIS_QUEUE_NAME } from './modules/analysis/analysis.constants';
import { ConnectionService } from './modules/global/database/connection.service';
import { REDIS_CLIENT } from './modules/global/redis/redis.constants';
import { SecretService } from './modules/global/secret/secret.service';
function createSecretServiceStub() {
return {
get: jest.fn((key: string) => {
if (key === 'REDIS_URL')
return Promise.resolve('redis://localhost:6379/0');
return Promise.resolve('');
}),
ready: jest.fn().mockResolvedValue(undefined),
};
}
describe('AppModule', () => {
it('compiles with the analysis queue module wired', async () => {
const moduleRef = await Test.createTestingModule({
imports: [AppModule],
})
.overrideProvider(SecretService)
.useValue(createSecretServiceStub())
.overrideProvider(ConnectionService)
.useValue({})
.overrideProvider(REDIS_CLIENT)
.useValue({
destroy: jest.fn(),
quit: jest.fn().mockResolvedValue(undefined),
})
.overrideProvider(getQueueToken(ANALYSIS_QUEUE_NAME))
.useValue({
add: jest.fn(),
})
.compile();
expect(moduleRef.get(AnalysisQueueService)).toBeInstanceOf(
AnalysisQueueService,
);
await moduleRef.close();
});
});
+2 -1
View File
@@ -1,10 +1,11 @@
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { AnalysisModule } from './modules/analysis/analysis.module';
import { GlobalModule } from './modules/global/global.module';
@Module({
imports: [GlobalModule],
imports: [GlobalModule, AnalysisModule],
controllers: [AppController],
providers: [AppService],
})
@@ -0,0 +1,355 @@
import { FEATURE_SCHEMA_VERSION } from '@persona-lenz/shared';
import type { ConnectionService } from '../global/database/connection.service';
import type { Account } from '../global/database/schemas';
import type { RiotApiClient } from '../riot/riot-api.client';
import type { UserAnalysisJobData } from './analysis.types';
import { FeatureExtractorService } from './feature-extractor.service';
import { AnalysisPipelineService } from './analysis-pipeline.service';
import { ProfileBuilderService } from './profile-builder.service';
function createJobData(): UserAnalysisJobData {
return {
gameName: 'Hide on bush',
tagLine: 'KR1',
platformRoute: 'kr',
regionalRoute: 'asia',
queueId: 420,
requestedMatchCount: 20,
};
}
function createMatchPayload(matchId = 'KR_1') {
return {
metadata: {
matchId,
participants: ['target-puuid', 'ally-puuid'],
},
info: {
gameCreation: 1_700_000_000_000,
gameDuration: 1800,
gameVersion: '26.13.123.456',
queueId: 420,
participants: [
{
puuid: 'target-puuid',
teamId: 100,
teamPosition: 'MIDDLE',
championId: 103,
kills: 6,
deaths: 2,
assists: 8,
totalDamageDealtToChampions: 24_000,
goldEarned: 12_000,
totalMinionsKilled: 210,
neutralMinionsKilled: 12,
visionScore: 24,
wardsKilled: 4,
detectorWardsPlaced: 3,
win: true,
challenges: {
kda: 7,
killParticipation: 0.7,
teamDamagePercentage: 0.32,
damagePerMinute: 800,
goldPerMinute: 400,
visionScorePerMinute: 0.8,
controlWardsPlaced: 3,
soloKills: 2,
},
},
{
puuid: 'ally-puuid',
teamId: 100,
teamPosition: 'JUNGLE',
championId: 64,
kills: 10,
totalDamageDealtToChampions: 30_000,
},
],
},
};
}
interface ExecQuery<T> {
exec: jest.Mock<Promise<T>, []>;
}
type AcknowledgedUpdate = { acknowledged: boolean };
type UpdateOneMock = jest.Mock<
ExecQuery<AcknowledgedUpdate>,
[Record<string, unknown>, Record<string, unknown>, Record<string, unknown>?]
>;
function asRecord(value: unknown): Record<string, unknown> {
if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
return value as Record<string, unknown>;
}
return {};
}
function execResolved<T>(value: T): ExecQuery<T> {
return { exec: jest.fn<Promise<T>, []>().mockResolvedValue(value) };
}
function leanExecResolved<T>(value: T) {
return {
lean: jest.fn(() => execResolved(value)),
};
}
function createStoredAccount(overrides: Partial<Account> = {}): Account {
return {
createdAt: new Date('2026-07-01T00:00:00.000Z'),
updatedAt: new Date('2026-07-01T00:00:00.000Z'),
puuid: 'target-puuid',
gameName: 'Hide on bush',
tagLine: 'KR1',
platformRoute: 'kr',
regionalRoute: 'asia',
profileIconId: 1,
summonerLevel: 500,
tiers: [],
isSeed: false,
...overrides,
};
}
interface PipelineHarnessOptions {
accountError?: Error;
existingMatchRaw?: Record<string, unknown> | null;
getMatch?: jest.Mock<Promise<Record<string, unknown>>, [string, string]>;
matchIds?: string[];
storedAccount?: Account;
}
function createPipelineHarness(options: PipelineHarnessOptions = {}) {
const updateAnalysisJob: UpdateOneMock = jest
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
.mockReturnValue(execResolved({ acknowledged: true }));
const findOneAndUpdateAccount = jest
.fn()
.mockReturnValue(
leanExecResolved(options.storedAccount ?? createStoredAccount()),
);
const updateAccount: UpdateOneMock = jest
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
.mockReturnValue(execResolved({ acknowledged: true }));
const findOneRiotMatch = jest
.fn()
.mockReturnValue(
leanExecResolved(
options.existingMatchRaw ? { raw: options.existingMatchRaw } : null,
),
);
const updateRiotMatch: UpdateOneMock = jest
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
.mockReturnValue(execResolved({ acknowledged: true }));
const updatePlayerMatchFeature: UpdateOneMock = jest
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
.mockReturnValue(execResolved({ acknowledged: true }));
const updatePlayerProfile: UpdateOneMock = jest
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
.mockReturnValue(execResolved({ acknowledged: true }));
const models = {
account: {
findOneAndUpdate: findOneAndUpdateAccount,
updateOne: updateAccount,
},
analysisJob: {
updateOne: updateAnalysisJob,
},
playerMatchFeature: {
updateOne: updatePlayerMatchFeature,
},
playerProfile: {
updateOne: updatePlayerProfile,
},
riotMatch: {
findOne: findOneRiotMatch,
updateOne: updateRiotMatch,
},
};
const connectionService = {
getModel: jest.fn((modelKey: keyof typeof models) =>
Promise.resolve(models[modelKey]),
),
} as unknown as ConnectionService;
const getAccountByRiotId = options.accountError
? jest.fn().mockRejectedValue(options.accountError)
: jest.fn().mockResolvedValue({
puuid: 'target-puuid',
gameName: 'Hide on bush',
tagLine: 'KR1',
});
const getMatch =
options.getMatch ??
jest
.fn<Promise<Record<string, unknown>>, [string, string]>()
.mockResolvedValue(createMatchPayload());
const riotApiClient = {
getAccountByRiotId,
getSummonerByPuuid: jest.fn().mockResolvedValue({
id: 'summoner-id',
puuid: 'target-puuid',
profileIconId: 1,
summonerLevel: 500,
}),
getLeagueEntriesByPuuid: jest.fn().mockResolvedValue([]),
getMatchIds: jest.fn().mockResolvedValue(options.matchIds ?? ['KR_1']),
getMatch,
} as unknown as RiotApiClient;
return {
findOneRiotMatch,
getMatch,
service: new AnalysisPipelineService(
connectionService,
riotApiClient,
new FeatureExtractorService(),
new ProfileBuilderService(),
),
updateAnalysisJob,
updatePlayerMatchFeature,
updatePlayerProfile,
updateRiotMatch,
};
}
describe('AnalysisPipelineService', () => {
it('fetches missing match details, stores features, builds a profile, and completes the job', async () => {
const {
findOneRiotMatch,
getMatch,
service,
updateAnalysisJob,
updatePlayerMatchFeature,
updatePlayerProfile,
updateRiotMatch,
} = createPipelineHarness();
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
expect(findOneRiotMatch).toHaveBeenCalledWith({ matchId: 'KR_1' });
expect(getMatch).toHaveBeenCalledWith('KR_1', 'asia');
const riotMatchUpdate = updateRiotMatch.mock.calls[0][1];
expect(riotMatchUpdate).toMatchObject({
$setOnInsert: {
matchId: 'KR_1',
queueId: 420,
},
});
const playerMatchFeatureUpdate = updatePlayerMatchFeature.mock.calls[0][1];
expect(playerMatchFeatureUpdate).toMatchObject({
$set: {
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
matchId: 'KR_1',
},
});
const playerProfileUpdate = updatePlayerProfile.mock.calls[0][1];
expect(playerProfileUpdate).toMatchObject({
$set: {
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
puuid: 'target-puuid',
sampleGameCount: 1,
},
});
const completedJobUpdate = updateAnalysisJob.mock.calls.find(
([, update]) => asRecord(asRecord(update).$set).status === 'completed',
);
expect(completedJobUpdate).toBeDefined();
expect(asRecord(asRecord(completedJobUpdate?.[1]).$set)).toMatchObject({
status: 'completed',
stage: 'completed',
});
});
it('completes without building a profile when no ranked matches are returned', async () => {
const { service, updateAnalysisJob, updatePlayerProfile } =
createPipelineHarness({
matchIds: [],
});
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
expect(updatePlayerProfile).not.toHaveBeenCalled();
const completedJobUpdate = updateAnalysisJob.mock.calls.find(
([, update]) => asRecord(asRecord(update).$set).status === 'completed',
);
expect(completedJobUpdate).toBeDefined();
});
it('uses cached match details without recalling Riot Match-V5', async () => {
const { getMatch, service, updatePlayerMatchFeature } =
createPipelineHarness({
existingMatchRaw: createMatchPayload(),
});
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
expect(getMatch).not.toHaveBeenCalled();
expect(updatePlayerMatchFeature).toHaveBeenCalledTimes(1);
});
it('skips individual match fetch failures and still builds from successful matches', async () => {
const getMatch = jest
.fn<Promise<Record<string, unknown>>, [string, string]>()
.mockRejectedValueOnce(new Error('temporary upstream failure'))
.mockResolvedValueOnce(createMatchPayload('KR_2'));
const { service, updatePlayerProfile } = createPipelineHarness({
getMatch,
matchIds: ['KR_1', 'KR_2'],
});
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
expect(getMatch).toHaveBeenCalledTimes(2);
const playerProfileUpdate = updatePlayerProfile.mock.calls[0][1];
expect(playerProfileUpdate).toMatchObject({
$set: {
sampleGameCount: 1,
},
});
});
it('does not mark the job failed before BullMQ exhausts retries', async () => {
const { service, updateAnalysisJob } = createPipelineHarness({
accountError: new Error('upstream unavailable'),
});
await expect(
service.processUserAnalysisJob(createJobData(), 'analysis-job-1', {
isFinalAttempt: false,
}),
).rejects.toThrow('upstream unavailable');
const failedJobUpdate = updateAnalysisJob.mock.calls.find(
([, update]) => asRecord(asRecord(update).$set).status === 'failed',
);
expect(failedJobUpdate).toBeUndefined();
});
it('marks the job failed with a public error on the final BullMQ attempt', async () => {
const { service, updateAnalysisJob } = createPipelineHarness({
accountError: new Error('internal host redis.local refused connection'),
});
await expect(
service.processUserAnalysisJob(createJobData(), 'analysis-job-1', {
isFinalAttempt: true,
}),
).rejects.toThrow('internal host redis.local refused connection');
const failedJobUpdate = updateAnalysisJob.mock.calls.find(
([, update]) => asRecord(asRecord(update).$set).status === 'failed',
);
expect(asRecord(asRecord(failedJobUpdate?.[1]).$set)).toMatchObject({
status: 'failed',
error: 'Analysis failed during processing.',
});
});
});
@@ -0,0 +1,456 @@
import { Injectable, Logger } from '@nestjs/common';
import { ConnectionService } from '../global/database/connection.service';
import type {
Account,
AnalysisJobStatus,
RiotMatch,
TierInfo,
} from '../global/database/schemas';
import {
RiotApiClient,
type RiotLeagueEntryDto,
} from '../riot/riot-api.client';
import {
normalizeRequestedMatchCount,
USER_ANALYSIS_JOB_NAME,
} from './analysis.constants';
import type {
ExtractedPlayerMatchFeature,
UserAnalysisJobData,
} from './analysis.types';
import { FeatureExtractorService } from './feature-extractor.service';
import { ProfileBuilderService } from './profile-builder.service';
interface MatchRecord {
matchId: string;
raw: Record<string, unknown>;
}
interface ParsedMatchSummary {
gameCreation: number;
gameDuration: number;
gameVersion?: string;
queueId?: number;
participantPuuids: string[];
}
function asRecord(value: unknown): Record<string, unknown> {
if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
return value as Record<string, unknown>;
}
return {};
}
function asNumber(value: unknown, fallback = 0): number {
return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
}
function asString(value: unknown): string | undefined {
return typeof value === 'string' ? value : undefined;
}
function asStringArray(value: unknown): string[] {
if (!Array.isArray(value)) return [];
return value.filter((item): item is string => typeof item === 'string');
}
function errorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
@Injectable()
export class AnalysisPipelineService {
private readonly logger = new Logger(AnalysisPipelineService.name);
constructor(
private readonly connectionService: ConnectionService,
private readonly riotApiClient: RiotApiClient,
private readonly featureExtractorService: FeatureExtractorService,
private readonly profileBuilderService: ProfileBuilderService,
) {}
public async processUserAnalysisJob(
data: UserAnalysisJobData,
jobId: string,
options: { isFinalAttempt?: boolean } = {},
): Promise<void> {
const normalizedData = {
...data,
requestedMatchCount: normalizeRequestedMatchCount(
data.requestedMatchCount,
),
};
try {
await this.updateJob(jobId, {
status: 'processing',
stage: 'resolve-account',
progress: {
fetchedMatches: 0,
totalMatches: 0,
},
});
const account = await this.resolveAndStoreAccount(normalizedData);
await this.updateJob(jobId, {
puuid: account.puuid,
stage: 'fetch-match-ids',
});
const matchIds = await this.riotApiClient.getMatchIds(account.puuid, {
count: normalizedData.requestedMatchCount,
queue: normalizedData.queueId,
regionalRoute: normalizedData.regionalRoute,
});
await this.updateJob(jobId, {
stage: 'fetch-match-details',
progress: {
fetchedMatches: 0,
totalMatches: matchIds.length,
},
});
if (matchIds.length === 0) {
await this.completeJob(jobId);
return;
}
const matchRecords = await this.fetchAndStoreMatches(
matchIds,
normalizedData,
jobId,
);
await this.updateJob(jobId, {
stage: 'extract-features',
});
const extractedFeatures = await this.extractAndStoreFeatures(
matchRecords,
account.puuid,
normalizedData.queueId,
);
await this.updateJob(jobId, {
stage: 'build-profile',
});
if (extractedFeatures.length > 0) {
await this.buildAndStoreProfile(
account,
normalizedData,
extractedFeatures,
);
}
await this.completeJob(jobId);
} catch (error) {
if (options.isFinalAttempt === true) {
await this.updateJob(jobId, {
status: 'failed',
error: this.publicErrorMessage(error),
});
}
throw error;
}
}
private async resolveAndStoreAccount(
data: UserAnalysisJobData,
): Promise<Account> {
const account = await this.riotApiClient.getAccountByRiotId(
data.gameName,
data.tagLine,
data.regionalRoute,
);
const [summoner, tiers] = await Promise.all([
this.riotApiClient.getSummonerByPuuid(account.puuid, data.platformRoute),
this.riotApiClient.getLeagueEntriesByPuuid(
account.puuid,
data.platformRoute,
),
]);
const accountModel = await this.connectionService.getModel('account');
const tierFetchedAt = new Date();
const storedAccount = await accountModel
.findOneAndUpdate(
{ puuid: account.puuid },
{
$set: {
puuid: account.puuid,
gameName: account.gameName,
tagLine: account.tagLine,
platformRoute: data.platformRoute,
regionalRoute: data.regionalRoute,
profileIconId: summoner.profileIconId,
summonerLevel: summoner.summonerLevel,
tiers: this.toTierInfo(tiers, tierFetchedAt),
tiersFetchedAt: tierFetchedAt,
},
$setOnInsert: {
isSeed: false,
},
},
{
new: true,
setDefaultsOnInsert: true,
upsert: true,
},
)
.lean<Account>()
.exec();
if (!storedAccount) {
throw new Error('Failed to store Riot account.');
}
return storedAccount;
}
private async fetchAndStoreMatches(
matchIds: string[],
data: UserAnalysisJobData,
jobId: string,
): Promise<MatchRecord[]> {
const matchRecords: MatchRecord[] = [];
const riotMatchModel = await this.connectionService.getModel('riotMatch');
for (const [index, matchId] of matchIds.entries()) {
try {
const existingMatch = await riotMatchModel
.findOne({ matchId })
.lean<RiotMatch>()
.exec();
if (existingMatch) {
if (this.isEligibleMatch(existingMatch.raw, data.queueId)) {
matchRecords.push({ matchId, raw: existingMatch.raw });
}
} else {
const rawMatch = await this.riotApiClient.getMatch(
matchId,
data.regionalRoute,
);
await this.storeRiotMatch(matchId, rawMatch);
if (this.isEligibleMatch(rawMatch, data.queueId)) {
matchRecords.push({ matchId, raw: rawMatch });
}
}
} catch (error) {
this.logger.warn(
`Skipping matchId="${this.safeLogText(matchId)}" after fetch/store failure: ${this.safeLogText(errorMessage(error))}`,
);
} finally {
await this.updateJob(jobId, {
progress: {
fetchedMatches: index + 1,
totalMatches: matchIds.length,
},
});
}
}
return matchRecords;
}
private async storeRiotMatch(
matchId: string,
rawMatch: Record<string, unknown>,
): Promise<void> {
const summary = this.parseMatchSummary(rawMatch);
const riotMatchModel = await this.connectionService.getModel('riotMatch');
await riotMatchModel
.updateOne(
{ matchId },
{
$setOnInsert: {
matchId,
gameCreation: summary.gameCreation,
gameDuration: summary.gameDuration,
gameVersion: summary.gameVersion,
queueId: summary.queueId,
participantPuuids: summary.participantPuuids,
raw: rawMatch,
fetchedAt: new Date(),
},
},
{ upsert: true },
)
.exec();
}
private async extractAndStoreFeatures(
matchRecords: MatchRecord[],
puuid: string,
queueId: number,
): Promise<ExtractedPlayerMatchFeature[]> {
const playerMatchFeatureModel =
await this.connectionService.getModel('playerMatchFeature');
const extractedFeatures: ExtractedPlayerMatchFeature[] = [];
for (const matchRecord of matchRecords) {
try {
const feature = this.featureExtractorService.extractPlayerMatchFeature(
matchRecord.raw,
puuid,
);
if (feature.queueId !== queueId) continue;
await playerMatchFeatureModel
.updateOne(
{ matchId: feature.matchId, puuid: feature.puuid },
{ $set: feature },
{ upsert: true },
)
.exec();
extractedFeatures.push(feature);
} catch (error) {
this.logger.warn(
`Skipping feature extraction for matchId="${this.safeLogText(matchRecord.matchId)}": ${this.safeLogText(errorMessage(error))}`,
);
}
}
return extractedFeatures;
}
private async buildAndStoreProfile(
account: Account,
data: UserAnalysisJobData,
extractedFeatures: ExtractedPlayerMatchFeature[],
): Promise<void> {
const profile = this.profileBuilderService.buildProfile({
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 },
{
$set: {
lastAnalyzedAt: analyzedAt,
},
},
)
.exec();
}
private async completeJob(jobId: string): Promise<void> {
await this.updateJob(jobId, {
status: 'completed',
stage: 'completed',
completedAt: new Date(),
error: undefined,
});
}
private async updateJob(
jobId: string,
patch: {
completedAt?: Date;
error?: string;
progress?: { fetchedMatches: number; totalMatches: number };
puuid?: string;
stage?: string;
status?: AnalysisJobStatus;
},
): Promise<void> {
const analysisJobModel =
await this.connectionService.getModel('analysisJob');
const set: Record<string, unknown> = {
jobId,
jobType: USER_ANALYSIS_JOB_NAME,
...patch,
};
const unset: Record<string, string> = {};
if (patch.error === undefined) {
delete set.error;
}
if (patch.status === 'completed') {
unset.error = '';
}
await analysisJobModel
.updateOne(
{ jobId },
{
$set: set,
...(Object.keys(unset).length > 0 ? { $unset: unset } : {}),
},
)
.exec();
}
private isEligibleMatch(
rawMatch: Record<string, unknown>,
queueId: number,
): boolean {
const info = asRecord(rawMatch.info);
return (
asNumber(info.queueId) === queueId && asNumber(info.gameDuration) >= 300
);
}
private parseMatchSummary(
rawMatch: Record<string, unknown>,
): ParsedMatchSummary {
const metadata = asRecord(rawMatch.metadata);
const info = asRecord(rawMatch.info);
return {
gameCreation: asNumber(info.gameCreation),
gameDuration: asNumber(info.gameDuration),
gameVersion: asString(info.gameVersion),
queueId:
typeof info.queueId === 'number' && Number.isFinite(info.queueId)
? info.queueId
: undefined,
participantPuuids: asStringArray(metadata.participants),
};
}
private toTierInfo(
entries: RiotLeagueEntryDto[],
fetchedAt: Date,
): TierInfo[] {
return entries.map((entry) => ({
queueType: entry.queueType,
tier: entry.tier,
rank: entry.rank,
leaguePoints: entry.leaguePoints,
wins: entry.wins,
losses: entry.losses,
fetchedAt,
}));
}
private publicErrorMessage(error: unknown): string {
if (
error instanceof Error &&
(error.name === 'RiotApiKeyError' ||
error.message.includes('Riot API key'))
) {
return 'Riot API key is invalid or expired.';
}
return 'Analysis failed during processing.';
}
private safeLogText(value: string): string {
return value.replace(/[\r\n\t]/gu, ' ').slice(0, 300);
}
}
@@ -0,0 +1,186 @@
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 { AnalysisQueueService } from './analysis-queue.service';
function createJobData(
overrides: Partial<UserAnalysisJobData> = {},
): UserAnalysisJobData {
return {
gameName: 'Hide on bush',
tagLine: 'KR1',
platformRoute: 'kr',
regionalRoute: 'asia',
queueId: 420,
requestedMatchCount: 20,
...overrides,
};
}
function createFindOneChain(
result: Pick<AnalysisJob, 'jobId' | 'status'> | null,
) {
const exec = jest
.fn<Promise<Pick<AnalysisJob, 'jobId' | 'status'> | null>, []>()
.mockResolvedValue(result);
const lean = jest.fn(() => ({ exec }));
const sort = jest.fn(() => ({ lean }));
return {
chain: { sort },
exec,
lean,
sort,
};
}
describe('AnalysisQueueService', () => {
it('creates an analysis job document and enqueues a BullMQ job', async () => {
const add = jest.fn().mockResolvedValue({ id: 'job-from-bull' });
const findOneChain = createFindOneChain(null);
const create = jest.fn().mockResolvedValue({});
const updateOne = jest.fn(() => ({
exec: jest.fn().mockResolvedValue({}),
}));
const analysisJobModel = {
create,
findOne: jest.fn(() => findOneChain.chain),
updateOne,
};
const connectionService = {
getModel: jest.fn().mockResolvedValue(analysisJobModel),
} as unknown as ConnectionService;
const service = new AnalysisQueueService(
{ add } as never,
connectionService,
() => 'analysis-job-1',
);
const result = await service.enqueueUserAnalysis(createJobData());
expect(result).toEqual({ jobId: 'analysis-job-1', status: 'queued' });
expect(create).toHaveBeenCalledWith(
expect.objectContaining({
jobId: 'analysis-job-1',
jobType: USER_ANALYSIS_JOB_NAME,
gameName: 'Hide on bush',
tagLine: 'KR1',
status: 'queued',
}),
);
expect(add).toHaveBeenCalledWith(
USER_ANALYSIS_JOB_NAME,
createJobData(),
expect.objectContaining({
attempts: 2,
jobId: 'analysis-job-1',
}),
);
});
it('returns an existing active job instead of enqueueing a duplicate', async () => {
const add = jest.fn();
const findOneChain = createFindOneChain({
jobId: 'existing-job',
status: 'processing',
});
const analysisJobModel = {
create: jest.fn(),
findOne: jest.fn(() => findOneChain.chain),
};
const connectionService = {
getModel: jest.fn().mockResolvedValue(analysisJobModel),
} as unknown as ConnectionService;
const service = new AnalysisQueueService(
{ add } as never,
connectionService,
() => 'new-job',
);
await expect(service.enqueueUserAnalysis(createJobData())).resolves.toEqual(
{
jobId: 'existing-job',
status: 'processing',
},
);
expect(add).not.toHaveBeenCalled();
expect(analysisJobModel.create).not.toHaveBeenCalled();
});
it('marks the pre-created job failed when BullMQ enqueue fails', async () => {
const add = jest.fn().mockRejectedValue(new Error('redis unavailable'));
const findOneChain = createFindOneChain(null);
const create = jest.fn().mockResolvedValue({});
const updateOne = jest.fn(() => ({
exec: jest.fn().mockResolvedValue({}),
}));
const analysisJobModel = {
create,
findOne: jest.fn(() => findOneChain.chain),
updateOne,
};
const connectionService = {
getModel: jest.fn().mockResolvedValue(analysisJobModel),
} as unknown as ConnectionService;
const service = new AnalysisQueueService(
{ add } as never,
connectionService,
() => 'analysis-job-1',
);
await expect(service.enqueueUserAnalysis(createJobData())).rejects.toThrow(
'redis unavailable',
);
expect(updateOne).toHaveBeenCalledWith(
{ jobId: 'analysis-job-1' },
{
$set: {
status: 'failed',
stage: 'enqueue',
error: 'redis unavailable',
},
},
);
});
it('serializes identical in-process requests before creating a duplicate job', async () => {
const add = jest.fn().mockResolvedValue({ id: 'analysis-job-1' });
let activeJob: Pick<AnalysisJob, 'jobId' | 'status'> | null = null;
const findOne = jest.fn(() => ({
sort: jest.fn(() => ({
lean: jest.fn(() => ({
exec: jest
.fn<Promise<Pick<AnalysisJob, 'jobId' | 'status'> | null>, []>()
.mockImplementation(() => Promise.resolve(activeJob)),
})),
})),
}));
const create = jest.fn().mockImplementation(() => {
activeJob = { jobId: 'analysis-job-1', status: 'queued' };
return Promise.resolve({});
});
const analysisJobModel = {
create,
findOne,
updateOne: jest.fn(),
};
const connectionService = {
getModel: jest.fn().mockResolvedValue(analysisJobModel),
} as unknown as ConnectionService;
const service = new AnalysisQueueService(
{ add } as never,
connectionService,
() => (create.mock.calls.length === 0 ? 'analysis-job-1' : 'unexpected'),
);
const [firstResult, secondResult] = await Promise.all([
service.enqueueUserAnalysis(createJobData()),
service.enqueueUserAnalysis(createJobData()),
]);
expect(firstResult).toEqual({ jobId: 'analysis-job-1', status: 'queued' });
expect(secondResult).toEqual({ jobId: 'analysis-job-1', status: 'queued' });
expect(create).toHaveBeenCalledTimes(1);
expect(add).toHaveBeenCalledTimes(1);
});
});
@@ -0,0 +1,159 @@
import { InjectQueue } from '@nestjs/bullmq';
import { Inject, Injectable } from '@nestjs/common';
import type { AnalysisRequestAcceptedDto } from '@persona-lenz/shared';
import type { Queue } from 'bullmq';
import { randomUUID } from 'node:crypto';
import { ConnectionService } from '../global/database/connection.service';
import type { AnalysisJob } from '../global/database/schemas';
import {
ANALYSIS_JOB_ID_FACTORY,
ACTIVE_ANALYSIS_JOB_STATUSES,
ANALYSIS_QUEUE_NAME,
normalizeRequestedMatchCount,
USER_ANALYSIS_JOB_NAME,
} from './analysis.constants';
import type { UserAnalysisJobData } from './analysis.types';
type JobIdFactory = () => string;
type ActiveAnalysisJob = Pick<AnalysisJob, 'jobId'> & {
status: Extract<AnalysisJob['status'], 'queued' | 'processing'>;
};
@Injectable()
export class AnalysisQueueService {
constructor(
@InjectQueue(ANALYSIS_QUEUE_NAME)
private readonly analysisQueue: Queue<
UserAnalysisJobData,
void,
typeof USER_ANALYSIS_JOB_NAME
>,
private readonly connectionService: ConnectionService,
@Inject(ANALYSIS_JOB_ID_FACTORY)
private readonly jobIdFactory: JobIdFactory = randomUUID,
) {}
public async enqueueUserAnalysis(
data: UserAnalysisJobData,
): Promise<AnalysisRequestAcceptedDto> {
const normalizedData = {
...data,
requestedMatchCount: normalizeRequestedMatchCount(
data.requestedMatchCount,
),
};
const duplicateRequestKey = this.duplicateRequestKey(normalizedData);
while (this.pendingDuplicateRequestKeys.has(duplicateRequestKey)) {
await this.sleep(10);
}
this.pendingDuplicateRequestKeys.add(duplicateRequestKey);
try {
return await this.enqueueUserAnalysisWithoutDuplicateRequestRace(
normalizedData,
);
} finally {
this.pendingDuplicateRequestKeys.delete(duplicateRequestKey);
}
}
private readonly pendingDuplicateRequestKeys = new Set<string>();
private async enqueueUserAnalysisWithoutDuplicateRequestRace(
normalizedData: UserAnalysisJobData,
): Promise<AnalysisRequestAcceptedDto> {
const analysisJobModel =
await this.connectionService.getModel('analysisJob');
const existingJob = await this.findActiveJob(
analysisJobModel,
normalizedData,
);
if (existingJob) {
return {
jobId: existingJob.jobId,
status: existingJob.status,
};
}
const jobId = this.jobIdFactory();
await analysisJobModel.create({
jobId,
jobType: USER_ANALYSIS_JOB_NAME,
gameName: normalizedData.gameName,
tagLine: normalizedData.tagLine,
platformRoute: normalizedData.platformRoute,
queueId: normalizedData.queueId,
requestedMatchCount: normalizedData.requestedMatchCount,
status: 'queued',
stage: 'queued',
progress: {
fetchedMatches: 0,
totalMatches: 0,
},
});
try {
await this.analysisQueue.add(USER_ANALYSIS_JOB_NAME, normalizedData, {
attempts: 2,
backoff: {
type: 'exponential',
delay: 1_000,
},
jobId,
});
} catch (error) {
await analysisJobModel
.updateOne(
{ jobId },
{
$set: {
status: 'failed',
stage: 'enqueue',
error: this.errorMessage(error),
},
},
)
.exec();
throw error;
}
return {
jobId,
status: 'queued',
};
}
private async findActiveJob(
analysisJobModel: Awaited<ReturnType<ConnectionService['getModel']>>,
data: UserAnalysisJobData,
): Promise<ActiveAnalysisJob | null> {
return analysisJobModel
.findOne({
gameName: data.gameName,
tagLine: data.tagLine,
platformRoute: data.platformRoute,
queueId: data.queueId,
status: { $in: ACTIVE_ANALYSIS_JOB_STATUSES },
})
.sort({ createdAt: -1 })
.lean<ActiveAnalysisJob>()
.exec();
}
private errorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
private duplicateRequestKey(data: UserAnalysisJobData): string {
return [
data.platformRoute,
data.queueId,
data.gameName.trim().toLocaleLowerCase(),
data.tagLine.trim().toLocaleLowerCase(),
].join(':');
}
private async sleep(durationMs: number): Promise<void> {
await new Promise((resolve) => setTimeout(resolve, durationMs));
}
}
@@ -0,0 +1,18 @@
export const ANALYSIS_QUEUE_NAME = 'analysis';
export const USER_ANALYSIS_JOB_NAME = 'user-analysis';
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 ACTIVE_ANALYSIS_JOB_STATUSES = ['queued', 'processing'] as const;
export function normalizeRequestedMatchCount(
requestedMatchCount: number,
): number {
if (!Number.isFinite(requestedMatchCount) || requestedMatchCount <= 0) {
return DEFAULT_ANALYSIS_MATCH_COUNT;
}
return Math.min(Math.trunc(requestedMatchCount), MAX_ANALYSIS_MATCH_COUNT);
}
@@ -0,0 +1,49 @@
import { BullModule } from '@nestjs/bullmq';
import { Module } from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import { DatabaseModule } from '../global/database/database.module';
import { SecretModule } from '../global/secret/secret.module';
import { SecretService } from '../global/secret/secret.service';
import { RiotModule } from '../riot/riot.module';
import { AnalysisQueueService } from './analysis-queue.service';
import {
ANALYSIS_JOB_ID_FACTORY,
ANALYSIS_QUEUE_NAME,
} from './analysis.constants';
import { AnalysisPipelineService } from './analysis-pipeline.service';
import { AnalysisProcessor } from './analysis.processor';
import { createBullMqOptions } from './bullmq.config';
import { FeatureExtractorService } from './feature-extractor.service';
import { ProfileBuilderService } from './profile-builder.service';
@Module({
imports: [
SecretModule,
DatabaseModule,
RiotModule,
BullModule.forRootAsync({
imports: [SecretModule],
inject: [SecretService],
useFactory: createBullMqOptions,
extraOptions: {
manualRegistration: process.env.NODE_ENV === 'test',
},
}),
BullModule.registerQueue({
name: ANALYSIS_QUEUE_NAME,
}),
],
providers: [
{
provide: ANALYSIS_JOB_ID_FACTORY,
useValue: randomUUID,
},
AnalysisQueueService,
AnalysisPipelineService,
AnalysisProcessor,
FeatureExtractorService,
ProfileBuilderService,
],
exports: [AnalysisQueueService, AnalysisPipelineService],
})
export class AnalysisModule {}
@@ -0,0 +1,117 @@
import type { Job } from 'bullmq';
import { USER_ANALYSIS_JOB_NAME } from './analysis.constants';
import type { UserAnalysisJobData } from './analysis.types';
import { AnalysisPipelineService } from './analysis-pipeline.service';
import { AnalysisProcessor } from './analysis.processor';
function createJobData(): UserAnalysisJobData {
return {
gameName: 'Hide on bush',
tagLine: 'KR1',
platformRoute: 'kr',
regionalRoute: 'asia',
queueId: 420,
requestedMatchCount: 20,
};
}
describe('AnalysisProcessor', () => {
it('delegates BullMQ jobs to the analysis pipeline', async () => {
const processUserAnalysisJob = jest
.fn<
Promise<void>,
[UserAnalysisJobData, string, { isFinalAttempt?: boolean }]
>()
.mockResolvedValue(undefined);
const processor = new AnalysisProcessor({
processUserAnalysisJob,
} as unknown as AnalysisPipelineService);
await processor.process({
attemptsMade: 1,
id: 'analysis-job-1',
name: USER_ANALYSIS_JOB_NAME,
opts: { attempts: 2 },
data: createJobData(),
} as Job<unknown>);
expect(processUserAnalysisJob).toHaveBeenCalledWith(
createJobData(),
'analysis-job-1',
{ isFinalAttempt: true },
);
});
it('rejects jobs without a BullMQ id', async () => {
const processor = new AnalysisProcessor({
processUserAnalysisJob: jest.fn(),
} as unknown as AnalysisPipelineService);
await expect(
processor.process({
data: createJobData(),
name: USER_ANALYSIS_JOB_NAME,
} as Job<unknown>),
).rejects.toThrow('Analysis job is missing a BullMQ job id.');
});
it('rejects unsupported job names before processing data', async () => {
const processUserAnalysisJob = jest.fn();
const processor = new AnalysisProcessor({
processUserAnalysisJob,
} as unknown as AnalysisPipelineService);
await expect(
processor.process({
id: 'analysis-job-1',
name: 'unexpected',
data: createJobData(),
} as Job<unknown>),
).rejects.toThrow('Unsupported analysis job name "unexpected".');
expect(processUserAnalysisJob).not.toHaveBeenCalled();
});
it('rejects malformed Redis payloads', async () => {
const processUserAnalysisJob = jest.fn();
const processor = new AnalysisProcessor({
processUserAnalysisJob,
} as unknown as AnalysisPipelineService);
await expect(
processor.process({
attemptsMade: 0,
id: 'analysis-job-1',
name: USER_ANALYSIS_JOB_NAME,
opts: { attempts: 2 },
data: {
...createJobData(),
regionalRoute: 'americas',
},
} as Job<unknown>),
).rejects.toThrow(
'Analysis job regionalRoute does not match platformRoute.',
);
expect(processUserAnalysisJob).not.toHaveBeenCalled();
});
it('normalizes requested match count from valid queue payloads', async () => {
const processUserAnalysisJob = jest.fn().mockResolvedValue(undefined);
const processor = new AnalysisProcessor({
processUserAnalysisJob,
} as unknown as AnalysisPipelineService);
await processor.process({
attemptsMade: 0,
id: 'analysis-job-1',
name: USER_ANALYSIS_JOB_NAME,
opts: { attempts: 2 },
data: createJobData({ requestedMatchCount: 999 }),
} as Job<unknown>);
expect(processUserAnalysisJob).toHaveBeenCalledWith(
createJobData({ requestedMatchCount: 50 }),
'analysis-job-1',
{ isFinalAttempt: false },
);
});
});
@@ -0,0 +1,127 @@
import { Processor, WorkerHost } from '@nestjs/bullmq';
import type { Job } from 'bullmq';
import {
ANALYSIS_QUEUE_NAME,
normalizeRequestedMatchCount,
USER_ANALYSIS_JOB_NAME,
} from './analysis.constants';
import { AnalysisPipelineService } from './analysis-pipeline.service';
import type { UserAnalysisJobData } from './analysis.types';
import {
RIOT_PLATFORM_ROUTES,
RIOT_REGIONAL_ROUTES,
toRegionalRoute,
type RiotPlatformRoute,
type RiotRegionalRoute,
} from '../riot/riot.types';
@Processor(ANALYSIS_QUEUE_NAME)
export class AnalysisProcessor extends WorkerHost {
constructor(
private readonly analysisPipelineService: AnalysisPipelineService,
) {
super();
}
public async process(job: Job<unknown>): Promise<void> {
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}".`);
}
const data = this.parseUserAnalysisJobData(job.data);
await this.analysisPipelineService.processUserAnalysisJob(data, job.id, {
isFinalAttempt: this.isFinalAttempt(job),
});
}
private parseUserAnalysisJobData(value: unknown): UserAnalysisJobData {
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
throw new Error('Analysis job data must be an object.');
}
const record = value as Record<string, unknown>;
const gameName = this.parseBoundedString(record.gameName, 'gameName', 64);
const tagLine = this.parseBoundedString(record.tagLine, 'tagLine', 16);
const platformRoute = this.parsePlatformRoute(record.platformRoute);
const regionalRoute = this.parseRegionalRoute(record.regionalRoute);
if (regionalRoute !== toRegionalRoute(platformRoute)) {
throw new Error(
'Analysis job regionalRoute does not match platformRoute.',
);
}
const queueId = this.parseQueueId(record.queueId);
const requestedMatchCount = this.parseRequestedMatchCount(
record.requestedMatchCount,
);
return {
gameName,
tagLine,
platformRoute,
regionalRoute,
queueId,
requestedMatchCount,
};
}
private parseBoundedString(
value: unknown,
fieldName: string,
maximumLength: number,
): string {
if (typeof value !== 'string') {
throw new Error(`Analysis job ${fieldName} must be a string.`);
}
const trimmed = value.trim();
if (trimmed.length === 0 || trimmed.length > maximumLength) {
throw new Error(`Analysis job ${fieldName} is out of range.`);
}
return trimmed;
}
private parsePlatformRoute(value: unknown): RiotPlatformRoute {
if (
typeof value !== 'string' ||
!RIOT_PLATFORM_ROUTES.includes(value as RiotPlatformRoute)
) {
throw new Error('Analysis job platformRoute is unsupported.');
}
return value as RiotPlatformRoute;
}
private parseRegionalRoute(value: unknown): RiotRegionalRoute {
if (
typeof value !== 'string' ||
!RIOT_REGIONAL_ROUTES.includes(value as RiotRegionalRoute)
) {
throw new Error('Analysis job regionalRoute is unsupported.');
}
return value as RiotRegionalRoute;
}
private parseQueueId(value: unknown): number {
if (value !== 420) {
throw new Error('Analysis job queueId is unsupported.');
}
return value;
}
private parseRequestedMatchCount(value: unknown): number {
if (typeof value !== 'number' || !Number.isFinite(value)) {
throw new Error('Analysis job requestedMatchCount must be finite.');
}
return normalizeRequestedMatchCount(value);
}
private isFinalAttempt(job: Job<unknown>): boolean {
const attempts =
typeof job.opts?.attempts === 'number' && job.opts.attempts > 0
? job.opts.attempts
: 1;
return job.attemptsMade + 1 >= attempts;
}
}
@@ -0,0 +1,52 @@
import type { Role } from '@persona-lenz/shared';
import type { TeamPositionOrUnknown } from '../global/database/schemas';
import type { RiotPlatformRoute, RiotRegionalRoute } from '../riot/riot.types';
export interface UserAnalysisJobData {
gameName: string;
tagLine: string;
platformRoute: RiotPlatformRoute;
regionalRoute: RiotRegionalRoute;
queueId: number;
requestedMatchCount: number;
}
export interface ExtractedPlayerMatchFeature {
matchId: string;
puuid: string;
queueId: number;
role: TeamPositionOrUnknown;
championId: number;
gameCreation: number;
gameDurationSec: number;
win: boolean;
patch: string;
features: Record<string, number>;
normalized: Record<string, number>;
vector: number[];
featureSchemaVersion: number;
normalizationMethod: 'registry-baseline';
confidence: number;
timelineProcessed: false;
}
export interface BuiltPlayerProfile {
puuid: string;
queueId: number;
mainRole: Role;
roleDistribution: Partial<Record<Role, number>>;
sampleGameCount: number;
championPool: Array<{
championId: number;
games: number;
wins: number;
}>;
profile: Record<string, number>;
vector: number[];
featureSchemaVersion: number;
normalizationMethod: 'registry-baseline';
confidence: number;
patches: string[];
lastMatchAt?: Date;
isSeed: boolean;
}
@@ -0,0 +1,54 @@
import {
createBullMqOptions,
resolveBullMqRedisConnection,
} from './bullmq.config';
describe('BullMQ config', () => {
it('parses redis URLs into BullMQ connection options', () => {
expect(
resolveBullMqRedisConnection('redis://worker:secret@redis.local:6380/2'),
).toMatchObject({
host: 'redis.local',
port: 6380,
username: 'worker',
password: 'secret',
db: 2,
maxRetriesPerRequest: null,
});
});
it('enables TLS for rediss URLs', () => {
expect(resolveBullMqRedisConnection('rediss://redis.local')).toMatchObject({
host: 'redis.local',
port: 6379,
tls: {},
});
});
it('rejects malformed Redis URLs without an explicit host', () => {
expect(() => resolveBullMqRedisConnection('redis:///0')).toThrow(
'REDIS_URL must include a hostname.',
);
});
it('creates root options from SecretService without exposing secrets', async () => {
const secretService = {
get: jest
.fn<Promise<string>, [string]>()
.mockResolvedValue('redis://localhost:6379/0'),
};
await expect(createBullMqOptions(secretService)).resolves.toMatchObject({
connection: {
host: 'localhost',
port: 6379,
db: 0,
maxRetriesPerRequest: null,
},
defaultJobOptions: {
attempts: 2,
},
});
expect(secretService.get).toHaveBeenCalledWith('REDIS_URL');
});
});
@@ -0,0 +1,73 @@
import type { BullRootModuleOptions } from '@nestjs/bullmq';
import type { QueueOptions } from 'bullmq';
import type { SecretService } from '../global/secret/secret.service';
export type BullMqConnectionOptions = NonNullable<QueueOptions['connection']>;
function parseRedisDatabase(pathname: string): number {
const trimmedPath = pathname.replace(/^\/+/u, '');
if (!trimmedPath) return 0;
const database = Number(trimmedPath);
if (!Number.isInteger(database) || database < 0) {
throw new Error('REDIS_URL must include a non-negative integer database.');
}
return database;
}
export function resolveBullMqRedisConnection(
redisUrl: string,
): BullMqConnectionOptions {
const parsedUrl = new URL(redisUrl);
if (parsedUrl.protocol !== 'redis:' && parsedUrl.protocol !== 'rediss:') {
throw new Error('REDIS_URL must use redis:// or rediss://.');
}
if (!parsedUrl.hostname) {
throw new Error('REDIS_URL must include a hostname.');
}
const connection: BullMqConnectionOptions = {
host: parsedUrl.hostname,
port: parsedUrl.port ? Number(parsedUrl.port) : 6379,
db: parseRedisDatabase(parsedUrl.pathname),
maxRetriesPerRequest: null,
};
if (parsedUrl.username) {
connection.username = decodeURIComponent(parsedUrl.username);
}
if (parsedUrl.password) {
connection.password = decodeURIComponent(parsedUrl.password);
}
if (parsedUrl.protocol === 'rediss:') {
connection.tls = {};
}
return connection;
}
export async function createBullMqOptions(
secretService: Pick<SecretService, 'get'>,
): Promise<BullRootModuleOptions> {
const redisUrl = await secretService.get<string>('REDIS_URL');
return {
connection: resolveBullMqRedisConnection(redisUrl),
defaultJobOptions: {
attempts: 2,
backoff: {
type: 'exponential',
delay: 1_000,
},
removeOnComplete: {
age: 86_400,
count: 1_000,
},
removeOnFail: {
age: 604_800,
count: 5_000,
},
},
};
}
@@ -0,0 +1,187 @@
import { FEATURE_SCHEMA_VERSION, METRICS } from '@persona-lenz/shared';
import { FeatureExtractorService } from './feature-extractor.service';
function createMatchPayload(overrides: Record<string, unknown> = {}) {
const currentPlayer = {
puuid: 'target-puuid',
teamId: 100,
teamPosition: 'MIDDLE',
championId: 103,
kills: 6,
deaths: 2,
assists: 8,
totalDamageDealtToChampions: 24_000,
goldEarned: 12_000,
totalMinionsKilled: 210,
neutralMinionsKilled: 12,
visionScore: 24,
wardsKilled: 4,
detectorWardsPlaced: 3,
win: true,
challenges: {
kda: 7,
killParticipation: 0.7,
teamDamagePercentage: 0.32,
damagePerMinute: 800,
goldPerMinute: 400,
visionScorePerMinute: 0.8,
controlWardsPlaced: 3,
dragonTakedowns: 1,
baronTakedowns: 1,
riftHeraldTakedowns: 0,
soloKills: 2,
},
};
return {
metadata: {
matchId: 'KR_1',
participants: ['target-puuid', 'ally-puuid', 'enemy-puuid'],
},
info: {
gameCreation: 1_700_000_000_000,
gameDuration: 1800,
gameVersion: '26.13.123.456',
queueId: 420,
participants: [
currentPlayer,
{
puuid: 'ally-puuid',
teamId: 100,
teamPosition: 'JUNGLE',
championId: 64,
kills: 10,
totalDamageDealtToChampions: 30_000,
},
{
puuid: 'enemy-puuid',
teamId: 200,
teamPosition: 'MIDDLE',
championId: 134,
kills: 4,
totalDamageDealtToChampions: 16_000,
},
],
...overrides,
},
};
}
describe('FeatureExtractorService', () => {
const service = new FeatureExtractorService();
it('extracts MVP 1 raw metrics and vector values in registry order', () => {
const feature = service.extractPlayerMatchFeature(
createMatchPayload(),
'target-puuid',
);
expect(feature.matchId).toBe('KR_1');
expect(feature.role).toBe('MIDDLE');
expect(feature.patch).toBe('26.13');
expect(feature.features).toMatchObject({
kda: 7,
killParticipation: 0.7,
damageShare: 0.32,
damagePerMin: 800,
goldPerMin: 400,
csPerMin: 7.4,
visionScorePerMin: 0.8,
wardsKilledPerMin: 4 / 30,
controlWardsPlaced: 3,
deathsPerMin: 2 / 30,
objectiveParticipation: 2,
soloKills: 2,
});
expect(feature.vector).toEqual(
METRICS.map((metric) => feature.normalized[metric.id]),
);
expect(feature.vector).toHaveLength(12);
expect(feature.featureSchemaVersion).toBe(FEATURE_SCHEMA_VERSION);
expect(feature.confidence).toBe(1);
});
it('falls back to manual calculations when challenges are missing', () => {
const payload = createMatchPayload({
participants: [
{
puuid: 'target-puuid',
teamId: 100,
teamPosition: 'MIDDLE',
championId: 103,
kills: 6,
deaths: 2,
assists: 8,
totalDamageDealtToChampions: 24_000,
goldEarned: 12_000,
totalMinionsKilled: 210,
neutralMinionsKilled: 12,
visionScore: 24,
wardsKilled: 4,
detectorWardsPlaced: 3,
win: true,
},
{
puuid: 'ally-puuid',
teamId: 100,
teamPosition: 'JUNGLE',
championId: 64,
kills: 14,
totalDamageDealtToChampions: 36_000,
},
],
});
const feature = service.extractPlayerMatchFeature(payload, 'target-puuid');
expect(feature.features.kda).toBe(7);
expect(feature.features.killParticipation).toBe(0.7);
expect(feature.features.damageShare).toBe(0.4);
expect(feature.features.damagePerMin).toBe(800);
expect(feature.features.goldPerMin).toBe(400);
expect(feature.features.controlWardsPlaced).toBe(3);
expect(feature.features.objectiveParticipation).toBe(0);
expect(feature.features.soloKills).toBe(0);
});
it('marks unknown roles and short games with lower confidence', () => {
const payload = createMatchPayload({
gameDuration: 900,
participants: [
{
puuid: 'target-puuid',
teamId: 100,
teamPosition: '',
championId: 103,
kills: 1,
deaths: 2,
assists: 1,
totalDamageDealtToChampions: 5_000,
goldEarned: 6_000,
totalMinionsKilled: 100,
neutralMinionsKilled: 0,
visionScore: 10,
wardsKilled: 1,
detectorWardsPlaced: 0,
win: false,
},
],
});
const feature = service.extractPlayerMatchFeature(payload, 'target-puuid');
expect(feature.role).toBe('UNKNOWN');
expect(feature.confidence).toBe(0.5);
});
it('marks known-role short games with short-game confidence only', () => {
const payload = createMatchPayload({
gameDuration: 900,
});
const feature = service.extractPlayerMatchFeature(payload, 'target-puuid');
expect(feature.role).toBe('MIDDLE');
expect(feature.confidence).toBe(0.8);
});
});
@@ -0,0 +1,218 @@
import {
FEATURE_SCHEMA_VERSION,
METRICS,
type MetricDefinition,
type Role,
} from '@persona-lenz/shared';
import { Injectable } from '@nestjs/common';
import type { TeamPositionOrUnknown } from '../global/database/schemas';
import type { ExtractedPlayerMatchFeature } from './analysis.types';
interface MatchParticipant {
assists?: number;
challenges?: Record<string, unknown>;
championId?: number;
deaths?: number;
detectorWardsPlaced?: number;
goldEarned?: number;
kills?: number;
neutralMinionsKilled?: number;
puuid?: string;
teamId?: number;
teamPosition?: string;
totalDamageDealtToChampions?: number;
totalMinionsKilled?: number;
visionScore?: number;
wardsKilled?: number;
win?: boolean;
}
interface MatchInfo {
gameCreation?: number;
gameDuration?: number;
gameVersion?: string;
participants?: MatchParticipant[];
queueId?: number;
}
interface MatchPayload {
info?: MatchInfo;
metadata?: {
matchId?: string;
};
}
const TEAM_POSITIONS = new Set<Role>([
'TOP',
'JUNGLE',
'MIDDLE',
'BOTTOM',
'UTILITY',
]);
function asRecord(value: unknown): Record<string, unknown> {
if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
return value as Record<string, unknown>;
}
return {};
}
function asNumber(value: unknown, fallback = 0): number {
return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
}
function fromChallenge(
challenges: Record<string, unknown>,
key: string,
): number | undefined {
const value = challenges[key];
return typeof value === 'number' && Number.isFinite(value)
? value
: undefined;
}
function ratio(numerator: number, denominator: number): number {
if (denominator <= 0) return 0;
return numerator / denominator;
}
function normalizeMetric(
metric: MetricDefinition,
role: Role,
rawValue: number,
): number {
const baseline = metric.baseline?.[role];
if (!baseline) return Math.max(0, Math.min(1, rawValue));
return Math.max(
0,
Math.min(1, (rawValue - baseline.min) / (baseline.max - baseline.min)),
);
}
function resolveRole(teamPosition: string | undefined): TeamPositionOrUnknown {
return TEAM_POSITIONS.has(teamPosition as Role)
? (teamPosition as Role)
: 'UNKNOWN';
}
function resolveNormalizationRole(role: TeamPositionOrUnknown): Role {
return role === 'UNKNOWN' ? 'MIDDLE' : role;
}
function resolvePatch(gameVersion: string | undefined): string {
const [major, minor] = (gameVersion ?? 'unknown').split('.');
if (!major || !minor) return 'unknown';
return `${major}.${minor}`;
}
@Injectable()
export class FeatureExtractorService {
public extractPlayerMatchFeature(
rawMatch: Record<string, unknown>,
puuid: string,
): ExtractedPlayerMatchFeature {
const payload = rawMatch as MatchPayload;
const info = payload.info ?? {};
const participants = info.participants ?? [];
const participant = participants.find(
(candidate) => candidate.puuid === puuid,
);
if (!participant) {
throw new Error(`Participant not found for puuid="${puuid}".`);
}
const gameDurationSec = asNumber(info.gameDuration);
const gameMinutes = Math.max(gameDurationSec / 60, 1);
const teamId = participant.teamId;
const teamParticipants = participants.filter(
(candidate) => candidate.teamId === teamId,
);
const teamKills = teamParticipants.reduce(
(sum, candidate) => sum + asNumber(candidate.kills),
0,
);
const teamDamage = teamParticipants.reduce(
(sum, candidate) => sum + asNumber(candidate.totalDamageDealtToChampions),
0,
);
const challenges = asRecord(participant.challenges);
const kills = asNumber(participant.kills);
const deaths = asNumber(participant.deaths);
const assists = asNumber(participant.assists);
const damage = asNumber(participant.totalDamageDealtToChampions);
const gold = asNumber(participant.goldEarned);
const minions =
asNumber(participant.totalMinionsKilled) +
asNumber(participant.neutralMinionsKilled);
const features: Record<string, number> = {
kda:
fromChallenge(challenges, 'kda') ??
(kills + assists) / Math.max(deaths, 1),
killParticipation:
fromChallenge(challenges, 'killParticipation') ??
ratio(kills + assists, teamKills),
damageShare:
fromChallenge(challenges, 'teamDamagePercentage') ??
ratio(damage, teamDamage),
damagePerMin:
fromChallenge(challenges, 'damagePerMinute') ?? damage / gameMinutes,
goldPerMin:
fromChallenge(challenges, 'goldPerMinute') ?? gold / gameMinutes,
csPerMin: minions / gameMinutes,
visionScorePerMin:
fromChallenge(challenges, 'visionScorePerMinute') ??
asNumber(participant.visionScore) / gameMinutes,
wardsKilledPerMin: asNumber(participant.wardsKilled) / gameMinutes,
controlWardsPlaced:
fromChallenge(challenges, 'controlWardsPlaced') ??
asNumber(participant.detectorWardsPlaced),
deathsPerMin: deaths / gameMinutes,
objectiveParticipation:
asNumber(challenges.dragonTakedowns) +
asNumber(challenges.baronTakedowns) +
asNumber(challenges.riftHeraldTakedowns),
soloKills: fromChallenge(challenges, 'soloKills') ?? 0,
};
const role = resolveRole(participant.teamPosition);
const normalizationRole = resolveNormalizationRole(role);
const normalized = Object.fromEntries(
METRICS.map((metric) => [
metric.id,
normalizeMetric(metric, normalizationRole, features[metric.id] ?? 0),
]),
);
return {
matchId: payload.metadata?.matchId ?? '',
puuid,
queueId: asNumber(info.queueId),
role,
championId: asNumber(participant.championId),
gameCreation: asNumber(info.gameCreation),
gameDurationSec,
win: participant.win === true,
patch: resolvePatch(info.gameVersion),
features,
normalized,
vector: METRICS.map((metric) => normalized[metric.id]),
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
normalizationMethod: 'registry-baseline',
confidence: this.resolveConfidence(role, gameDurationSec),
timelineProcessed: false,
};
}
private resolveConfidence(
role: TeamPositionOrUnknown,
gameDurationSec: number,
): number {
let confidence = 1;
if (role === 'UNKNOWN') confidence = Math.min(confidence, 0.5);
if (gameDurationSec < 1200) confidence = Math.min(confidence, 0.8);
return confidence;
}
}
@@ -0,0 +1,109 @@
import { FEATURE_SCHEMA_VERSION, METRICS } from '@persona-lenz/shared';
import type { PlayerMatchFeature } from '../global/database/schemas';
import { ProfileBuilderService } from './profile-builder.service';
function createFeature(
overrides: Partial<PlayerMatchFeature> = {},
): PlayerMatchFeature {
const normalized = Object.fromEntries(
METRICS.map((metric) => [metric.id, 0.5]),
);
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: 1800,
win: true,
patch: '26.13',
features: {},
normalized,
vector: METRICS.map((metric) => normalized[metric.id]),
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
normalizationMethod: 'registry-baseline',
confidence: 1,
timelineProcessed: false,
...overrides,
};
}
describe('ProfileBuilderService', () => {
const service = new ProfileBuilderService();
it('builds a confidence-weighted profile in registry vector order', () => {
const firstNormalized = Object.fromEntries(
METRICS.map((metric, index) => [metric.id, 0.8 - index * 0.01]),
);
const secondNormalized = Object.fromEntries(
METRICS.map((metric, index) => [metric.id, 0.2 + index * 0.01]),
);
const firstFeature = createFeature({
matchId: 'KR_1',
role: 'MIDDLE',
championId: 103,
win: true,
normalized: firstNormalized,
confidence: 1,
patch: '26.13',
gameCreation: 1_700_000_000_000,
});
firstFeature.vector = METRICS.map(
(metric) => firstFeature.normalized[metric.id],
);
const secondFeature = createFeature({
matchId: 'KR_2',
role: 'BOTTOM',
championId: 22,
win: false,
normalized: secondNormalized,
confidence: 0.5,
patch: '26.14',
gameCreation: 1_700_100_000_000,
});
secondFeature.vector = METRICS.map(
(metric) => secondFeature.normalized[metric.id],
);
const profile = service.buildProfile({
features: [firstFeature, secondFeature],
isSeed: false,
puuid: 'target-puuid',
queueId: 420,
});
expect(profile.mainRole).toBe('MIDDLE');
expect(profile.sampleGameCount).toBe(2);
for (const metric of METRICS) {
expect(profile.profile[metric.id]).toBeCloseTo(
(firstNormalized[metric.id] + secondNormalized[metric.id] * 0.5) / 1.5,
);
}
expect(profile.vector).toEqual(
METRICS.map((metric) => profile.profile[metric.id]),
);
expect(profile.championPool).toEqual([
{ championId: 103, games: 1, wins: 1 },
{ championId: 22, games: 1, wins: 0 },
]);
expect(profile.patches).toEqual(['26.13', '26.14']);
expect(profile.lastMatchAt).toEqual(new Date(1_700_100_000_000));
expect(profile.confidence).toBeCloseTo(0.3);
});
it('throws when no features are available', () => {
expect(() =>
service.buildProfile({
features: [],
isSeed: false,
puuid: 'target-puuid',
queueId: 420,
}),
).toThrow('Cannot build a profile without match features.');
});
});
@@ -0,0 +1,137 @@
import {
FEATURE_SCHEMA_VERSION,
METRICS,
type Role,
} from '@persona-lenz/shared';
import { Injectable } from '@nestjs/common';
import type { PlayerMatchFeature } from '../global/database/schemas';
import type { BuiltPlayerProfile } from './analysis.types';
type ProfileSourceFeature = Pick<
PlayerMatchFeature,
| 'championId'
| 'confidence'
| 'gameCreation'
| 'normalized'
| 'patch'
| 'role'
| 'win'
>;
export interface BuildProfileParams {
features: ProfileSourceFeature[];
isSeed: boolean;
puuid: string;
queueId: number;
}
const ROLE_ORDER: Role[] = ['TOP', 'JUNGLE', 'MIDDLE', 'BOTTOM', 'UTILITY'];
function isRole(value: string): value is Role {
return ROLE_ORDER.includes(value as Role);
}
@Injectable()
export class ProfileBuilderService {
public buildProfile(params: BuildProfileParams): BuiltPlayerProfile {
if (params.features.length === 0) {
throw new Error('Cannot build a profile without match features.');
}
const totalConfidence = params.features.reduce(
(sum, feature) => sum + feature.confidence,
0,
);
const safeTotalConfidence = Math.max(totalConfidence, Number.EPSILON);
const profile = Object.fromEntries(
METRICS.map((metric) => [
metric.id,
params.features.reduce(
(sum, feature) =>
sum + (feature.normalized[metric.id] ?? 0) * feature.confidence,
0,
) / safeTotalConfidence,
]),
);
const roleCounts = new Map<Role, number>();
const championPool = new Map<
number,
{ championId: number; games: number; wins: number }
>();
for (const feature of params.features) {
if (isRole(feature.role)) {
roleCounts.set(feature.role, (roleCounts.get(feature.role) ?? 0) + 1);
}
const championEntry = championPool.get(feature.championId) ?? {
championId: feature.championId,
games: 0,
wins: 0,
};
championEntry.games += 1;
if (feature.win) championEntry.wins += 1;
championPool.set(feature.championId, championEntry);
}
const knownRoleGameCount = [...roleCounts.values()].reduce(
(sum, count) => sum + count,
0,
);
const roleDistribution = Object.fromEntries(
[...roleCounts.entries()].map(([role, count]) => [
role,
count / Math.max(knownRoleGameCount, 1),
]),
) as Partial<Record<Role, number>>;
const averageConfidence = totalConfidence / params.features.length;
const sampleSizeConfidenceMultiplier = Math.min(
params.features.length / 5,
1,
);
return {
puuid: params.puuid,
queueId: params.queueId,
mainRole: this.resolveMainRole(roleCounts),
roleDistribution,
sampleGameCount: params.features.length,
championPool: [...championPool.values()].sort(
(left, right) =>
right.games - left.games ||
right.wins - left.wins ||
left.championId - right.championId,
),
profile,
vector: METRICS.map((metric) => profile[metric.id]),
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
normalizationMethod: 'registry-baseline',
confidence: averageConfidence * sampleSizeConfidenceMultiplier,
patches: [
...new Set(params.features.map((feature) => feature.patch)),
].sort(),
lastMatchAt: new Date(
Math.max(...params.features.map((feature) => feature.gameCreation)),
),
isSeed: params.isSeed,
};
}
private resolveMainRole(roleCounts: Map<Role, number>): Role {
let selectedRole: Role = 'MIDDLE';
let selectedCount = -1;
for (const role of ROLE_ORDER) {
const count = roleCounts.get(role) ?? 0;
if (count > selectedCount) {
selectedRole = role;
selectedCount = count;
}
}
return selectedRole;
}
}
+17
View File
@@ -1,11 +1,14 @@
import { getQueueToken } from '@nestjs/bullmq';
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import request from 'supertest';
import { App } from 'supertest/types';
import { configureApp } from './../src/app.setup';
import { AppModule } from './../src/app.module';
import { ANALYSIS_QUEUE_NAME } from './../src/modules/analysis/analysis.constants';
import { ConnectionService } from './../src/modules/global/database/connection.service';
import { REDIS_CLIENT } from './../src/modules/global/redis/redis.constants';
import { SecretService } from './../src/modules/global/secret/secret.service';
describe('AppController (e2e)', () => {
let app: INestApplication<App>;
@@ -16,11 +19,25 @@ describe('AppController (e2e)', () => {
})
.overrideProvider(ConnectionService)
.useValue({})
.overrideProvider(SecretService)
.useValue({
get: jest.fn((key: string) => {
if (key === 'REDIS_URL') {
return Promise.resolve('redis://localhost:6379/0');
}
return Promise.resolve('');
}),
ready: jest.fn().mockResolvedValue(undefined),
})
.overrideProvider(REDIS_CLIENT)
.useValue({
destroy: jest.fn(),
quit: jest.fn().mockResolvedValue(undefined),
})
.overrideProvider(getQueueToken(ANALYSIS_QUEUE_NAME))
.useValue({
add: jest.fn(),
})
.compile();
app = moduleFixture.createNestApplication();